Stochastic simulations
=========================

Once a model is solved, RISE exposes a small set of stochastic-analysis
routines on the model object. All of them share the same convention:
the return type is a struct of ``ts`` (RISE time-series) objects keyed
by endogenous-variable name, with multiple pages when there are
multiple parameterizations or solution branches.

Artificial data
-------------------

``simulate`` returns simulated time series from the solved model::

    sim = simulate(m, 'simul_periods', 200);

    plot(sim.PAI, sim.Y)

The most relevant options:

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - Option
     - Effect
   * - ``simul_periods``
     - Number of periods to simulate (default ``100``).
   * - ``simul_burn``
     - Burn-in periods discarded from the head of the returned series
       (default ``0``).
   * - ``simul_seed``
     - Seed forwarded to MATLAB's RNG before drawing. ``[]`` keeps the
       current state.
   * - ``simul_shock_uncertainty``
     - When ``true`` (default), draws structural shocks from their
       declared distributions; when ``false``, sets every shock to its
       mean and returns the deterministic continuation.
   * - ``simul_historical_data``
     - Initial conditions and / or a conditioning path. Accepts a
       struct of ``ts`` or a :doc:`simulation plan <simulation_plans>`.

The output struct is suitable for fan charts, regime-conditioning
diagnostics, and as data for an estimation step. Pages of the returned
``ts`` correspond to the model's parameterizations.

Pruned simulations
-------------------

RISE implements 5-th order approximation of the perturbation solution
of regime-switching DSGE models. At order :math:`\geq 2` the
straight-perturbation simulation is not guaranteed to be bounded: an
unlucky shock realisation can send the state off to ``inf``. The
pruning algorithm of :cite:`AndreasenJFVRR2013`, generalised to
regime-switching models, removes the unbounded higher-order terms at
simulation time without changing the policy function. Pruning is on by
default at order :math:`\geq 2` and can be controlled via the standard
solve / simulate options.

Theoretical and Simulated moments
------------------------------------

For a *linear* solved model the unconditional first and second moments
are available in closed form via the Lyapunov equation. RISE exposes
them through ``theoretical_autocovariances`` (and the
``theoretical_autocorrelations`` convenience wrapper)::

    [Acov, info, retcode] = theoretical_autocovariances(m, 10);
    Acorr                 = theoretical_autocorrelations(m, 'autocorr_ar', 10);

For higher-order or regime-switching models, where closed-form moments
are not available, the standard practice is to simulate a long path
with ``simulate`` and compute sample moments from the returned
``ts`` (``cov``, ``corrcoef``, ``var`` overloaded on ``ts``). The two
should agree at order 1 up to Monte Carlo error.

Variance decomposition
---------------------------

``variance_decomposition`` returns the share of forecast-error variance
attributable to each structural shock, at each horizon, for each
endogenous variable::

    vd = variance_decomposition(m);

The output is a struct of ``ts`` (one entry per endogenous variable)
where each ``ts`` carries one column per shock and one row per horizon
(``conditional``) or a single row for the unconditional decomposition
(``unconditional``). It is available for the linear (order-1) solution
of constant-parameter and regime-switching models.

Impulse responses
--------------------

``irf`` returns impulse responses on the solved model::

    myirfs = irf(m);

The output is a struct of ``ts`` keyed by *shock name*; each entry is
itself a struct of ``ts`` keyed by *endogenous variable*. ``quick_irfs``
(see :doc:`../../Plotting tools`) lays the result out in a publication
grid.

Simple Impulse Responses
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

"Simple" IRFs trace the model's response to a one-time, one-shock
deviation from a fixed initial state (typically the unconditional
mean or the deterministic steady state). For a linear model the simple
IRF is the same regardless of initial state and shock sign, so it is
the natural default. The main controls are:

- ``irf_periods`` (default ``40``): horizon.
- ``irf_shock_sign`` and ``irf_shock_scale``: sign and size of the
  impulse. Use ``-1`` for a contractionary shock and ``2`` to feed a
  two-standard-deviation impulse instead of the default one.
- ``solve_shock_horizon``: anticipation horizon. With a strictly
  positive value the IRF traces the response to a shock that is
  *announced* the corresponding number of periods ahead (the
  "anticipation" pattern); with ``0`` the shock is unanticipated.
- *Delayed reaction* of the response is obtained by appending zero
  realisations to the shock path through a :doc:`simulation plan
  <simulation_plans>`. The same plan, with ``simplan.anticipate(true)``
  vs ``anticipate(false)``, produces the *anticipated* and
  *unanticipated* variants.

Generalized Impulse Responses
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For nonlinear or regime-switching models, the simple IRF depends on
the initial state and on whether the shock is positive or negative,
small or large. The *generalized* impulse response (GIRF), defined as
the difference between the conditional expectation of the path with a
given shock and without, averaged over the model's stationary
distribution of states, is the right object to look at. Switch ``irf``
into GIRF mode via::

    girf = irf(m, 'irf_type', 'girf', 'irf_draws', 1000);

``irf_draws`` controls the number of state-and-shock realisations
averaged. The cost scales linearly with ``irf_draws``; values in the
low thousands are usually enough for smooth output.